---
title: Astro 사이트를 Github Pages에 배포하세요
description: Github Pages를 사용하여 Astro 사이트를 웹에 배포하는 방법
sidebar:
  label: GitHub Pages
type: deploy
logo: github
supports: ['static'] 
i18nReady: true
---
import { Steps } from '@astrojs/starlight/components';

[GitHub Pages](https://pages.github.com/)를 사용하면 [GitHub Actions](https://github.com/features/actions)를 사용하여 [GitHub.com](https://github.com/)의 리포지토리에서 직접 미리 렌더링된 정적 Astro 웹사이트를 호스팅할 수 있습니다.

## 배포 방법

Astro는 아주 적은 구성으로 [프로젝트를 GitHub Pages에 배포할 수 있는 공식 Astro GitHub Action](https://github.com/withastro/action)을 유지 관리하며, 이는 권장되는 배포 방법입니다.

아래 지침에 따라 GitHub Action을 사용하여 Astro 사이트를 GitHub Pages에 배포하세요. 이렇게 하면 GitHub URL (예: `https://<username>.github.io/<my-repo>`)의 리포지토리에서 웹사이트가 만들어집니다. 배포가 완료되면 선택적으로 [사용자 정의 도메인을 구성](#github-url을-사용자-정의-도메인으로-변경하기)하여 원하는 도메인 (예: `https://example.com`)에 GitHub Pages 사이트를 배포할 수 있습니다.

<Steps>
1. 프로젝트의 `.github/workflows/deploy.yml`에 새 파일을 만들고 아래 YAML에 붙여넣습니다.

    ```yaml title="deploy.yml"
    name: Deploy to GitHub Pages

    on:
      # 'main' 브랜치로 푸시할 때마다 워크플로를 트리거합니다.
      # 다른 브랜치 이름을 사용하시나요? `main`을 브랜치 이름으로 바꾸세요.
      push:
        branches: [ main ]
      # GitHub의 Actions 탭에서 이 워크플로를 수동으로 실행할 수 있습니다.
      workflow_dispatch:
      
    # 이 작업이 리포지토리를 복제하고 페이지 배포를 생성하도록 허용합니다.
    permissions:
      contents: read
      pages: write
      id-token: write

    jobs:
      build:
        runs-on: ubuntu-latest
        steps:
          - name: Checkout your repository using git
            uses: actions/checkout@v5
          - name: Install, build, and upload your site
            uses: withastro/action@v5
            # with:
              # path: . # 저장소 내 Astro 프로젝트의 루트 위치입니다. (선택 사항)
              # node-version: 24 # 사이트를 빌드하는 데 사용해야 하는 특정 버전의 Node입니다. 기본값은 22입니다. (선택 사항)
              # package-manager: pnpm@latest # 종속성을 설치하고 사이트를 빌드하는 데 사용해야 하는 노드 패키지 관리자입니다. lockfile을 기반으로 자동으로 감지됩니다. (선택 사항)
              # build-cmd: pnpm run build # 사이트를 빌드하는 데 실행할 명령입니다. 기본적으로 패키지 빌드 스크립트/작업을 실행합니다. (선택 사항)
            # env:
              # PUBLIC_POKEAPI: 'https://pokeapi.co/api/v2' # 변수 값에는 작은따옴표를 사용합니다. (선택 사항)

      deploy:
        needs: build
        runs-on: ubuntu-latest
        environment:
          name: github-pages
          url: ${{ steps.deployment.outputs.page_url }}
        steps:
          - name: Deploy to GitHub Pages
            id: deployment
            uses: actions/deploy-pages@v4
    ```
    
    선택적 입력으로 Astro 액션을 구성할 수 있습니다. 사용하려는 입력과 `with:` 줄의 주석을 해제하여 입력값을 제공하세요.
        
    사이트에 공개 환경 변수가 필요한 경우 `env:` 줄의 주석을 해제하고 여기에 값을 추가하세요. (비공개 환경 변수를 추가하는 방법은 [비밀 설정에 대한 GitHub 문서](https://docs.github.com/ko/actions/how-tos/write-workflows/choose-what-workflows-do/use-variables#creating-configuration-variables-for-a-repository)를 참조하세요.)
    
    :::caution
    공식 Astro [action](https://github.com/withastro/action)은 lockfile을 검색하여 선호하는 패키지 관리자(`npm`, `yarn`, `pnpm`, `bun`)를 감지합니다. 패키지 관리자가 자동으로 생성한 `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lockb` 파일을 저장소에 커밋해야 합니다.
    :::

2. Astro 구성 파일에서 [`site`](/ko/reference/configuration-reference/#site)를 배포한 사이트의 GitHub URL로 설정합니다.

    ```js title="astro.config.mjs" ins={4}
    import { defineConfig } from 'astro/config'
    
    export default defineConfig({
      site: 'https://astronaut.github.io',
    })
    ```
    
    `site` 값은 다음 중 하나여야 합니다.

    - 사용자 이름을 기반으로 하는 URL: `https://<username>.github.io`
    - [GitHub 조직의 비공개 페이지](https://docs.github.com/ko/enterprise-cloud@latest/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site)에 사용할 수 있는 자동 생성된 임의의 URL: `https://<random-string>.pages.github.io/`

3. `astro.config.mjs`에서 [`base`](/ko/reference/configuration-reference/#base) 값을 구성합니다. (일반적으로 필수)
      
      GitHub Pages는 사용자 이름과 리포지토리 이름에 따라 달라지는 주소 (예: `https://<username>/github.io/<my-repo>/`)에 웹사이트를 게시합니다. 웹사이트의 리포지토리를 지정하는 `base` 값을 설정합니다. 이는 Astro에게 웹사이트의 루트가 기본값인 `/`가 아닌 `/my-repo`임을 알려주기 위한 것입니다. 리포지토리 이름이 `<username>.github.io` 패턴 (예: `https://github.com/username/username.github.io/`)과 일치하는 경우 이 단계를 건너뛸 수 있습니다.
      
      `base`를 슬래시 (예: `/my-repo`)로 시작하는 리포지토리의 이름으로 구성합니다.

      ```js title="astro.config.mjs" ins={4-5}
      import { defineConfig } from 'astro/config'
  
      export default defineConfig({
        site: 'https://astronaut.github.io',
        base: '/my-repo',
      })
      ```

      :::caution[`base`가 구성된 내부 링크]      
      이 값을 구성하면 모든 내부 페이지 링크 앞에 `base` 값을 붙여야 합니다.

      ```astro ins="/my-repo"
      <a href="/my-repo/about">About</a>
      ```
      
      [`base` 값 구성](/ko/reference/configuration-reference/#base)에 대해 자세히 알아보세요.
      :::

4. GitHub에서 리포지토리의 **Settings** 탭으로 이동하여 **Pages** 섹션을 찾습니다.

5. 사이트의 **Source**로 **GitHub Actions**를 선택합니다.

</Steps>

Astro 프로젝트의 리포지토리에 변경 사항을 푸시하면 GitHub Action이 자동으로 GitHub URL에 배포합니다.

## Github URL을 사용자 정의 도메인으로 변경하기

이전 지침에 따라 Astro 프로젝트가 [GitHub URL의 GitHub Pages에 배포되면](#배포-방법) 사용자 정의 도메인을 구성할 수 있습니다. 즉, 사용자는 `https://<username>.github.io` 대신 사용자 정의 도메인인 `https://example.com`에서 사이트를 방문할 수 있습니다.

<Steps>

1. [도메인 공급업체의 DNS를 구성합니다](https://docs.github.com/ko/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain).
2. 프로젝트에 `./public/CNAME` 레코드를 추가합니다.
    
    `public/` 폴더에 사용자 정의 도메인을 지정하는 한 줄의 텍스트가 포함된 다음 파일을 만듭니다.

    ```js title="public/CNAME"
    sub.example.com
    ```
    
    이렇게 하면 `user.github.io` 대신 사용자 정의 도메인에 사이트를 배포합니다.

3. Astro 구성에서 `site` 값을 사용자 정의 도메인으로 업데이트합니다. `base` 값은 설정하지 말고, 이미 존재한다면 제거하세요.

    ```js title="astro.config.mjs" ins={4} del={5}
    import { defineConfig } from 'astro/config'

    export default defineConfig({
      site: 'https://example.com',
      base: '/my-repo'
    })
    ```

4. 필요한 경우 모든 페이지 내부 링크를 업데이트하여 `base` 접두사를 제거합니다.

    ```astro del="/my-repo"
    <a href="/my-repo/about">About</a>
    ```

</Steps>

## 예시

- [Github Pages 배포 시작 템플릿](https://github.com/hkbertoson/github-pages)
- [Starlight Flexoki 테마 (프로덕션 사이트)](https://delucis.github.io/starlight-theme-flexoki/)
- [Expressive Code Color Chips (프로덕션 사이트)](https://delucis.github.io/expressive-code-color-chips/)
- [Starlight Markdown Blocks (프로덕션 사이트)](https://delucis.github.io/starlight-markdown-blocks/)
